Pure utility that derives an EPICS PV prefix from a controller path:
the first segment (controller id) is used verbatim, while later segments
are converted snake_case -> PascalCase. EPICS adopts this in #354 to
replace the existing root-prefix-plus-pascalled-path approach for
multi-controller IOCs.

D2 module of #353.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Reject controller ids that aren't safe in a REST URL path: empty or
containing characters outside the loosest URL-safe set
([A-Za-z0-9_-]+). The error message includes the offending id so
startup failures are unambiguous. Hookup into RestTransport.connect
follows in the multi-controller routing slice.

D3-REST module of #353.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Every transport's connect() now takes list[ControllerAPI] uniformly. The
existing single-controller transports (EPICS CA, EPICS PVA, GraphQL,
Tango, REST) accept a list-of-one via a shared _expect_single helper
and behave as before. FastCS.serve passes [self.controller_api]. True
multi-controller support per transport will be wired in subsequent
slices.

This is a pure refactor: existing tests are updated to the new
list-of-one call shape, no behaviour changes for any transport.

Part of #353.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

RestServer now accepts list[ControllerAPI] and adds attribute and
command routes for each. RestTransport hooks validate_rest_id into
connect() so illegal ids fail fast with a clear startup error. Existing
path-based routing already prefixes routes with controller_api.path[0],
so once Controller.set_id seeds the API path, REST URLs become
GET /{id}/{sub}/{attr} for free.

Two new tests in tests/test_multi_controller.py cover routing two
distinct ids in one process and rejecting an id with an illegal
character.

Part of #353.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

`launch()` now accepts either a single Controller class or a list of
classes; the generated `fastcs.yaml` schema replaces the top-level
`controller:` key with a dict of `controllers:` keyed by id. Each value
carries a `type:` discriminator (defaults to the class `__name__`,
overridable via `type_name: ClassVar[str]`) and an optional `controller:`
options block. Single-class registration may omit `type:` via a default.
Duplicate ids are rejected at YAML load time by ruamel's safe loader.

Wiring through `FastCS` for >1 controller lands in the next slice; for
now multi-entry configs validate cleanly but the run command exits with
a clear LaunchError pointing at the deferred work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

EpicsCATransport now hosts every configured controller in a single
softioc, with each controller's id used verbatim as its PV prefix.
EpicsCAIOC takes list[ControllerAPI] and loops the existing
record/PVI/command builders per controller, deriving each prefix from
pv_prefix_from_path(api.path) (the D2 utility introduced in #353).
EpicsCATransport.connect drops _expect_single in favour of true
multi-controller; validate_ca_id runs at connect time and rejects ids
with illegal characters as well as setups whose longest derivable PV
prefix already exceeds the 60-character EPICS limit.

EpicsIOCOptions and its pv_prefix field are deleted. EpicsCAOptions and
EpicsPVAOptions empty placeholders preserve epicsca: / epicspva: as
fastcs.yaml discriminator keys (Pydantic union resolution is
positional, so a unique field name per transport is still load-bearing).
EpicsGUI no longer takes a separate prefix argument; PVs derive from
the controller path. PVA temporarily continues via _expect_single but
adopts pv_prefix_from_path so it gets the same id-based prefix and no
longer needs EpicsIOCOptions; full PVA multi-root work lands in #355.

tests/test_multi_controller.py grows a CA two-controllers-no-clash
scenario and a CA id-validation fail-fast case. tests/example_softioc,
tests/example_p4p_ioc, tests/benchmarking/controller, tests/conftest,
test_initial_value, test_p4p, test_softioc, test_gui, test_pva_gui and
the AssertableControllerAPI fixture all migrate to id-based naming
(controllers set their id, transports take no prefix). Demo
controller.yaml and both regenerated schema.json files reflect the new
EpicsCAOptions / EpicsPVAOptions schemas and removal of pv_prefix.
The 13 docs/snippets are exercised by tests/test_docs_snippets.py via
runpy, so they migrate in this commit too to keep the suite green at
every commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

multiple-transports.md and launch-framework.md still showed
EpicsIOCOptions(pv_prefix=...) in their Python and YAML examples.
Replace those with the id-based shape: controllers set their id (or
inherit it from the YAML controllers: dict key), and EpicsCATransport /
EpicsPVATransport take no prefix argument. The prose follows the API
that landed in the previous commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

EpicsPVATransport now hosts every configured controller in one p4p
server, with each controller's id used verbatim as its PV prefix.
P4PIOC takes list[ControllerAPI] and builds one StaticProvider per
controller via the existing parse_attributes helper, so each controller
gets an independent :PVI root with no super-parent (per the PRD).
EpicsPVATransport.connect drops _expect_single in favour of true
multi-controller; validate_pva_id runs at connect time and rejects ids
with illegal characters as well as setups whose longest derivable PV
prefix already exceeds the 60-character EPICS limit.

validate_pva_id mirrors validate_ca_id and lives in transports/epics/
pva/util.py to keep id validation a per-transport concern. To share the
60-char constant without a cross-transport import, EPICS_MAX_NAME_LENGTH
moves up from ca/util.py to epics/util.py; ca/util.py re-imports it so
existing ca.util consumers (ca/ioc.py, test_softioc) are unaffected.

tests/test_multi_controller.py grows a PVA two-controllers-distinct-PVI
scenario (asserts each StaticProvider exposes its own root) and a PVA
id-validation fail-fast case. test_pva_util.py mirrors test_ca_util.py's
validator coverage. test_p4p.py::test_pvi_grouping shortens its UUID id
to 8 hex chars so the deepest derived prefix
(<id>:AdditionalChild:ChildChild) no longer trips the new 60-char check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sphinx is configured with `nitpicky = True` and `--fail-on-warning`, so
single-backticks in the new P4PIOC docstring (`StaticProvider`, `:PVI`)
were treated as :any: cross-references and failed to resolve. Switch to
double-backticks so they're inline literals instead.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Wires the GraphQL transport into the multi-controller foundation:

- New `validate_graphql_id` enforces GraphQL `Name` syntax (the most
  restrictive of FastCS's transports — drives the lowest-common-denominator
  id-naming guidance for users mixing transports).
- `GraphQLServer` now accepts `list[ControllerAPI]` and assembles a single
  combined schema with one top-level Query (and Mutation, where applicable)
  field per controller id. Sub-API type names are path-joined to keep two
  controllers' identically-named sub-controllers from clashing in the schema.
- `GraphQLTransport.connect` validates ids fail-fast at startup.
- `tests/test_multi_controller.py` gains a two-controller combined-schema
  scenario and a per-transport id-validation case.
- The single-controller transport test is updated to namespace its queries
  under a controller id, matching the new contract; a latent bug in its
  `nest_mutation` helper (recursing through `nest_query`) is fixed in passing.
- `docs/how-to/multiple-transports.md` adds a charset table and notes
  GraphQL as the lowest common denominator for cross-transport ids.

D4 of #351 lands as a single transport-level module. Both EPICS
transports now invoke `emit_gui_files(controller_apis, options, builder)`
once with the full controller list, replacing the per-controller loop
that wrote everything to the same file. The module produces:

- One screen/docs file per controller at `output_dir/{id}.{ext}`,
  preserving the order in which controllers were declared in
  `fastcs.yaml`.
- An index file at the root of `output_dir` -- emitted even for a
  single controller, so the file layout is stable as the controller
  count changes.

The GUI index uses pvi's `DLSFormatter` directly (rather than the
convenience `format_index` wrapper) so that `DeviceRef.name` can be
coerced to satisfy pvi's `PascalStr` constraint when controller ids
legitimately start with a digit (e.g. UUID-flavoured test prefixes).
The docs side mirrors the GUI shape with a minimal markdown emitter --
just enough to lift `EpicsDocs.create_docs` off its prior no-op stub.

Knock-on schema/option changes:

- `EpicsGUIOptions.output_path` (single file) becomes `output_dir`
  (directory); ditto `EpicsDocsOptions.path` -> `output_dir`. The
  per-controller filename is derived from the controller id.
- The bundled demo, the 13 docs snippets, `tests/example_softioc.py`,
  the multi-transport how-to and the `launch-framework` how-to all
  migrate to the new field name. Both `schema.json` files are
  regenerated.
- `EpicsGUI` loses its `create_gui()` file-writing entry point in
  favour of a smaller `build_device(title) -> Device` helper that the
  emission module composes per controller.
- `tests/data/config.yaml` drops its `gui: {}` / `docs: {}` blocks --
  they were schema-fixture noise that now leaks generated files into
  the repo CWD when the launcher tests exercise `connect()`.

Tests:

- New `tests/transports/epics/test_emission.py` (D4 unit tests):
  per-id files plus index for single and multi-controller cases,
  declaration order preservation, missing-output-dir creation, PVA
  builder propagation, and the digit-leading-id coercion.
- `tests/transports/epics/ca/test_gui.py` gains a transport-level
  assertion that the index file is generated alongside per-controller
  files (per #358 acceptance criteria).
- `tests/test_multi_controller.py` gains a CA scenario that drives
  `EpicsCATransport.connect` end-to-end and asserts both per-id and
  index files for GUI and docs land in their configured `output_dir`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Previously the discriminator defaulted to the registered class's
discriminator when only one Controller class was registered, so single-
class apps could omit `type:`. Mandate it everywhere: `type:` becomes
required regardless of how many classes are registered.

Self-describing YAML — external tooling can identify each entry's class
without knowing how `launch()` was called — and one consistent shape
across single- and multi-class apps.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

pyright (CI lint job) flagged the previous approach of stashing
``fastcs_controller_class`` and ``fastcs_options_type`` directly on
each dynamically-built Entry model class as
``reportAttributeAccessIssue``. Replace with a module-level
``_ENTRY_REGISTRY`` dict mapping Entry class → (Controller class,
options-type), mirroring the ``Transport.subclasses`` pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The py:obj nitpick_ignore entry for
fastcs.transports.epics.util.controller_pv_prefix was added when the
docs build emitted a warning for that symbol. The symbol's referencing
context was removed in c8adb33, so the ignore entry no longer
suppresses anything and is dead config.

Fixes #364

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The "Hosting multiple controllers" subsection of `docs/how-to/launch-framework.md`
introduced its yaml example by claiming the bundled demo
(`python -m fastcs.demo run src/fastcs/demo/fastcs.yaml`) hosted two
`DeviceController` instances on different ports. The actual demo hosts two
`TemperatureController` instances with nested `ip_settings` and
`num_ramp_controllers` options on the same IP but different ports — so the
prose did not match the code it pointed at.

Reframe the example as a generic `DeviceController` illustration (consistent
with the rest of the file's placeholder), and add a separate one-liner
pointing readers at `src/fastcs/demo/fastcs.yaml` for a real working example.
The yaml block itself is unchanged.

Fixes #370

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Each docs/snippets/*.py wired up an EPICS CA transport but never called
controller.set_id(...). The snippets compiled and tests passed because
runpy only executes the module body — fastcs.run() lives behind the
if __name__ == "__main__": guard, so transport.connect never fires
and pv_prefix_from_path([]) never raises. A reader who copy-pastes a
snippet and tries to actually run it would hit ValueError: Cannot
derive a PV prefix from an empty path the moment FastCS starts.

Extract the controller into a local before constructing FastCS and
call controller.set_id("DEMO") so each snippet now matches the runtime
contract documented in docs/how-to/multiple-transports.md and
docs/how-to/launch-framework.md.

Fixes #363

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Remove the `if api.path:` guard around `validate_graphql_id(api.path[0])`
in `GraphQLTransport.connect`. REST, EPICS CA, EPICS PVA and Tango all
call `path[0]` unconditionally — a controller without a leading id is a
configuration bug, not a path GraphQL should silently accept while the
others reject.

The other half of #366 — adding the 60-char PV-name limit to the PVA
row of the charset table in `docs/how-to/multiple-transports.md` —
was already applied as a drive-by in 207d68d (Tango multi-device
per controller with id in device name).

Fixes #366

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

`_instantiate_controllers` previously inferred whether a Controller
class takes an options arg by checking `options_type is None` — the
build-time decision in `_build_entry_model` had to stay implicit and
in sync with this check. Replace the registry's `(cls, options_type)`
tuple with a `_RegisteredClass` dataclass that carries an explicit
`expects_options: bool` alongside the class and options-type, so the
runtime branch reads off the same source of truth as the build-time
one.

Fixes #361

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

`tango_dev_class_name` collapses hyphens to underscores so that a
controller id like `DEV-1` and `DEV_1` both sanitise to the same Python
class name `DEV_1`. `tango.server.run` then registers two Tango device
classes under that name and silently keeps only the second, so one of
the controllers vanishes from the device server with no diagnostic.

Catch this at the same boundary as the existing per-id Tango
validation: `TangoTransport.connect` now records every sanitised class
name it has seen and raises `ValueError` naming both colliding ids when
a second id maps onto an existing one. `validate_tango_id` is
deliberately left accepting hyphens — the underlying id is still legal,
only the post-sanitisation class name clashes.

Fixes #371

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

validate_ca_id and validate_pva_id were byte-for-byte identical except
for their per-transport regex constant and the "EPICS CA id" /
"EPICS PVA id" label in the illegal-characters error message. Move the
structural skeleton into transports/epics/util.py as
validate_epics_pv_id, parameterised on transport_label and id_re. Each
transport's validator becomes a 3-line wrapper that supplies its own
_CA_ID_RE / _PVA_ID_RE and label, so the regex constants stay
co-located with their transport and can diverge later if either side
needs to tighten or loosen its alphabet.

Error messages and validation behaviour are identical; existing tests
in tests/transports/epics/ca/test_ca_util.py and
tests/transports/epics/pva/test_pva_util.py pass unchanged.

Fixes #365

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The previous commit hoisted the shared EPICS id-validation skeleton
into ``transports/epics/util.py`` but dropped the
``EPICS_MAX_NAME_LENGTH`` import from ``ca/util.py``, breaking
consumers that imported it from the CA module's namespace
(``ca/ioc.py`` and ``tests/transports/epics/ca/test_softioc.py``).
Point those consumers at the canonical home in
``transports/epics/util`` instead of restoring the re-export.

Fixes #365

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The `src/fastcs/transports/epics/docs.py` module had already been reduced
to a re-export shim for `emit_docs_files` and `EpicsDocsOptions`, with
nothing in `src/`, `tests/`, or `docs/` importing from it. The CA and
PVA transports both call `emit_docs_files` directly from
`fastcs.transports.epics.emission` (which carries the real per-controller
docs emission added in slice #358), and `EpicsDocsOptions` is re-exported
from `.options` via `transports/epics/__init__.py`. Deleting the shim
removes the last vestige of the old `EpicsDocs.create_docs` no-op stub.

Fixes #367

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The IOC publishes PVs using the controller id verbatim (see
pv_prefix_from_path in transports/epics/util.py), but the per-controller
DeviceRef in the GUI index was upper-casing the id when writing the pv
attribute. For id="alpha" the per-controller .bob referenced alpha:Foo
(matching the IOC) while the index .bob referenced ALPHA, which the IOC
never publishes. Drop the .upper() so the index agrees with the IOC.

Fixes #368

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The EPICS CA id validator accepts `[A-Za-z0-9_-]+`, so ids like `"___"`
and `"-"` pass validation and reach `_coerce_pascal_name` in the GUI
emission path. That helper delegates to `pvi.device.enforce_pascal_case`,
which strips non-Pascal characters and unconditionally indexes `s[0]` on
the result. When every character is stripped the index raises
`IndexError`, blowing up GUI emission at `connect()` time with an opaque
traceback.

Pre-strip the id with the same regex pvi uses (`NON_PASCAL_CHARS_RE`)
and raise `ValueError` with a message that names the offending id when
the strip yields the empty string. Choosing fail-fast over an `"X"`
fallback keeps the failure traceable: a silent fallback would generate
nonsense GUI names that the user would have to reverse-engineer back to
the bad id.

Fixes #369

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>